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SunView 1.80 Update 


The major features of SunView 1.80 are described in detail here: 

□ an online help mechanism, allowing application developers to provide Spot 
Help for their users, 

□ programmable alarms for dramatically notifying users, 

□ keyboard support 

- type 4 keyboard 

- upgraded description of the . textswrc file 

□ enhanced color capabilities 

- colored panel items, 

- support for 24-bit true color, 

□ changes to the defaults database 

□ several user changes, 

□ various bug fixes. 

Not described in this Update are changes to the Defaults Editor database or new 
user features, which are contained in the SunView User’s Guide. 

Note that there is not a separate update document for the SunView System 
Programmer’s Guide, the information for which appears here. 

D.l. SunView Help The new release of SunView offers two related mechanisms for providing online 

Mechanism help to users: 

□ Spot Help, a cursor-position sensitive facility to display one 32 x 80 charac¬ 
ter panel of online help, 

□ More Help, to provide additional information when the one panel of Spot 
help is not enough. 



l 
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Basics of Spot Help in 
SunView 1.80 


Help Keys 


Limitations of Spot Help 


The Help Directory 


To get help, the user places the pointer over the object (panel, button, etc) of 
inquiry and then strikes the I Help 1 key. Whatever information is available is 
then displayed. 

On a Type3 keyboard, the Help Key is I Meta-/1 , obtained by pressing the (Metal 
key and the CD key at the same time. There are two Meta keys, which are 
immediately to the left and right of the long space bar on the bottom center of the 
keyboard. 

On a type 4 keyboard, the 1 Meta-/1 combination works, and there is an explicit 
(Hein) key also. 

□ The (Metal keys are in the same place as on the Type 3 keyboard, beside the 
space bar, marked with a diamond, ♦. 

a [ Help 1 is the double-width key located at the bottom of the left hand block of 
function keys (the ones labeled I Stop 1 , 1 Again 1 , etc). 

There are two limitations to the use of Spot Help on SunView 1.80: 

□ At this time, only the mechanism for Spot Help is provided; no actual Help 
Text is provided. Available resources do not allow the development of Help 
Text for SunView itself, but the mechanism is being made available to 
developers who want to provide cursor-position sensitive help in their appli¬ 
cations. 

□ Also note that Spot Help supports a single window of text, 32 lines by about 
80 characters (longer lines are not supported at this time). To obtain longer 
messages, you must use the More Help feature. This is a user implemented 
feature called by the More button on the help window. See More Help, 
below. 

A new category of defaults, Help, has been added to Default Editor to 
support Spot Help. Inside this category, the default Help/Directory is used 
to identify the directory where Help Text for an application resides. By default, 
this directory is /usr/lib/help, but it can be changed to any directory. 


Help Text: A Simple Example The following simple experiment will show you how to add Help Text for a Sun¬ 
View text subwindow. This experiment is intended only as a quick way to see 
the action of Spot Help. 


Bring up a tool that uses a text subwindow ( textedit , or mailtool, for 
example). Place the cursor in the subwindow and press I Help 1 . You should see a 
message saying: 


r 


- 


No help is available for textsw:textsw. 




J 


To remedy this, create a file named text sw. info in the /usr/lib/help 
directory. (You can create the file anywhere else if you remember to change the 
Defaults Editor Help/Directory entry to point to it.) Put in the key 
: textsw and the Help Text you want. For example: 
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Now bring up a new tool containing a text subwindow, again position the cursor 
in the window, and press I Help I . 

This time you should see the text you entered in the file. 


You can do this for any feature in SunView: put the cursor over the item and 
press I Help 1 to see the message: 



In the example, the filename and the key were both textsw. In general, of 
course, this is not the case. 

Create (or append to) a file named package . inf o an entry following the key¬ 
word '.feature. 

The . info file has the following format: 

# comments 

:keywordl [ keyword! [ keyword3 ] ] [ :more_help_key ] 

message text 

You can include comment lines in your .info files by preceding them with the 
number sign. Use an initial colon to denote a line containing a keyword or key¬ 
words. If several keywords pertain to the same help message, place them on the 
same line, with spaces separating them. The message text supplied appears in the 
Spot Help window whenever this .info file and keywordl, keyword !, or key¬ 
words are values for the HELP_DATA attribute. 

Several examples of .info files are shown below, following the discussion of 
the Spot Help mechanism. 

Spot Help Program Interface This section explains how to create Spot Help messages for text subwindow, 

panel, canvas, alert, tty, and menu window objects, as well as for individual 
menu, scroll bar, and panel items. It assumes you are familiar with SunView pro¬ 
gramming concepts; for more information, consult the SunView Programmer’s 
Guide 

The two basic steps to include Spot Help for a window object are: 

1. Add the help_data attribute to the object or to an item within the object. 
You can add this attribute like other SunView attributes, such as through a 
null-terminated attribute list 

2. Write the help file in the format specified above. 
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When a user presses the key, the HELP_DATA attribute is retrieved from the 
current window or item. The text specified by the HELP_DATA value is then 
displayed in the Spot Help window. 


The value for the HELP DATA attribute must be a two-part string, enclosed in 
quotation marks, in the format: 



file is the name of the text file containing the help description, file must be 
located in the default help directory and must end with the suffix .info (such as 
myapplication. info). Although all Spot Help files must end with the 
. info extension, include only the base of the file name, not the extension, as 
the value of the HELP_DATA attribute. The Help mechanism automatically 
appends" the .info extension to the file name that you supply, and then looks 
in the default help directory (/usr/ lib/ help initially) for that file. 

keyword is a word within the . info file that is associated with the specific 
help text that will appear when help is requested. Each . inf o file can contain 
multiple keywords, but no two keywords can be alike within the same .info 
file. 

For example, a HELP_DATA attribute could be 



When help is requested on this object, the Help facility: 

1. Finds the accounting. inf o file. 

2. Locates the keyword w4. 

3. Displays the text associated with that keyword in a Spot Help window. 

The .info File Format section contains more details about the structure and 
placement of . inf o file text. The next section describes how you can use the 
HELP_DATA attribute to make your Spot Help messages more helpful for users. 

Providing More Specific Spot You can change the HELP_DATA attribute of various window objects to suit par- 
Help ticular circumstances, for instance if a menu item is active or disabled, or a frame 

is open or iconic. If you do, you can provide users with more context-sensitive 
Spot Help, as described in this section. 

HELP_DATA for Active and For example, you might give all disabled objects (such as greyed-out menu 

Disabled Objects items) a new help_data attribute where you disable them in the code, and 

again where you activate them, as described below: 
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' ■ 

/* this menu item invokes a save 
Menu item mi_save; 

function */ 

1 

/* here the save function becomes 
menu_set (mi_save, MENU_INACTIVE, 

disabled */ 

TRUE, 


HELPDATA, "myapp:mi_save_disabled" , 

0); 



/* and here it becomes active */ 
menu set (mi save, MENU INACTIVE, 

FALSE, 


HELP DATA, "myapp:mi_save" , 

0) ; 

l_ 


j 


A corresponding Spot Help message for the “save” function above could be: 

-- 

Save menu item 

Stores the current version of the file you have loaded. 

^ _ > 


The Spot Help message when the save function is disabled could be: 

- - 

Save menu item [DISABLED] 

Stores the current version of the file you have loaded. 

This item is disabled because you have not loaded a file. 

s_> 


The myapp .info file to display the above messages would look like 


t - 






a 

:mi save 







Save menu item 

Stores the current version 

of 

the 

file 

you 

have 

loaded. 

: mi_s a ve__di s abled 







Save menu item [DISABLED] 
Stores the current version 

of 

the 

file 

you 

have 

loaded. 

This item is disabled because 

you 

have 

not 

loaded a file. 







J 


Alternatively, a single message might be used to cover Spot Help for both situa¬ 
tions. This is achieved by a multiple-key entry in the myapp. info file, such 
as: 


t - 





■\ 

:mi_save mi save disabled 






Save menu item 

Stores the current version of 

the 

file 

you have 

loaded. 


This item is disabled if you 

have 

not 

loaded a 

file. 


v 





_> 
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You also could include HELP_DATA attributes for frames that are open and 
those that are icons (closed). The following sample program creates a base frame 
and then interposes an event function in front of the frame’s normal event 
handler. This makes the program aware of when the frame opens or closes, as 
well as when the program should change the frame’s HELP_DATA attribute. 


♦include <suntool/sunview.h> 
♦include <suntool/help.h> 
♦include <stdio.h> 
main(argc, argv) 

int argc; 

char **argv; 

{ 


Frame frame; 

Notify_value sample_interpose(); 

/* create frame using command-line arguments */ 
frame = window_create(0, FRAME, FRAME_ARGS, 
argc, argv, 0) ; 

/* set HELP_DATA depending on whether frame is 
open or iconic */ 

if ((int)window_get(frame, FRAME_CLOSED)) { 

window_set(frame, 


HELP_DATA, "progname:frame_iconic" , 

0 ); 

} else { 

window_set(frame, 

HELP_DATA, "prognamerframe" , 

0 ); 

} 

/* interpose in order to spot future open/close events */ 
(void)notify_interpose_event_func(frame, 
sample_interpose, NOTIFY_SAFE); 
window_main_loop(frame); 

} 

static Notify__value 

sample_interpose(frame, event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

{ 

int initial_state, current_state; 

Notify_value value; 

/* get frame's state */ 

initial_state = (int)window_get(frame,FRAME_CLOSED); 

/* handle the event */ 

value = notify_next_event_func(frame, event,arg, type); 

/* if frame's state has changed, change HELP_DATA */ 
current_state = (int)window_get(frame,FRAME_CLOSED); 


sun 
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if (initial_state != current_state) { 

if (current_state) { window_set(frame, 

HELP_D AT A," progname: frame_icon ic" , 

0 ); 

} else { window_set(frame, 

HELP_DATA, ,, progname:frame H , 

0 ); 

} 

} 

return(value); 

} 

v_> 


Spot Help Example 


The following program puts up a SunView window with several panel items and 
buttons and Spot Help for them. 


The beginning of the main loop 
includes some header files and 
defines some storage and some 
SunView objects. 


/* client.c 

* Constructs a simple panel, showing use of 

* HELP_DATA attributes. 

*/ 

#include <stdio.h> 

#include <suntool/sunview.h> 

#include <suntool/panel.h> 

♦include <suntool/help.h> 

main(argc, argv) 


int 

argc; 

char 

**argv 

Frame 

frame; 

Panel 

panel; 




Revision A of March 27,1990 





8 SunView 1.80 Update 


Note the use of the help_data 
attribute here. This is where the 
link to the Help Text in the file is 
actually made. 


f - 

frame = window__create (NULL, FRAME, 

FRAME_LABEL, a rgv[0], 

FRAME_ARGS, argc, argv. 

-V 

"HELPDATA, "clientrframe" , 

0) ; 

panel = window create(frame, PANEL, 

WIN_WIDTH, 200, 

WIN_HEIGHT, 200, 


"HELP DATA, "clientrpanel" , 

0); 

panel_create item(panel, PANEL TEXT, 
PANEL_LABEL_STRING, "Year:", 

PANEL_VALUE, "1988", 


HELP DATA, "client:year" , 

0) ; 

panel_create_item(panel, PANEL TEXT, 

P ANE L_L ABE L_S T RING, "Maker:", 

PANEL_VALUE, "Ford", 


HELP DATA, "clientrmaker" , 

0); 

panel create item (panel, PANEL_TEXT, 
PANEL_LABEL_STRING, "Model:", 

PANEL_VALUE, "Escort", 


HELP DATA, "client:model" , 

0) ; 
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Note also that there are no callback 
procedures defined for the buttons. 
In a more real-life example, of 
course they would be used. 


r 



panel__create item (panel, PANEL BUTTON, 
PANEL_LABEL__IMAGE, 

panel__button image (panel, "Find", 0, 

0), 


HELP DATA, "clientrfind button" , 

PANE L_ITEM_X, 40, 

PANEL ITEM Y, 160, 

0); 

panel_create_item(panel, PANEL BUTTON, 
PANEL_LABEL_IMAGE, 

panel button image(panel, "Done", 0, 

0), 


HELP DATA, 

PANEL ITEM X, 110, 

PANEL ITEM Y, 160, 

0); 

window_fit(frame); 
window main loop(frame); 

} 


j 


The following is the client. inf o file containing the Help Text for the 
client “application”. The point is to notice how the keys in this file are del¬ 
imited (:) and how they connect the text in this file to the objects in client. c 
marked with the HELP_DATA attribute. 

Most of the keys in this example also have a second colon (:) and a second 
string associated with them. This string is used to invoke More Help, the second 
feature of the SunView 1.80 help mechanism. 

Note the : f ind_button keyword. It has no text, but does have a second 
colon and string following it. This is a shortcut to More Help. 
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You have to include the blank lines 
if you want spacing in the Spot Help 
message. 


:frame 

:More_About_the_Frame 

Sample Help Client 

This is the client's frame. 

:panel 

:More_About_the_PaneI 

Sample Help Client 

This is the client's panel. 

:year: 

More_About_the_Year_FieId 

Sample Help Client 

This is the client's 'Year' field. 


:maker: 

Sample Help Client 

This is the client's 'Maker' field. 
(Notice that 'More Help' is not provided 
for this item.) 

:model 

:More_About_the_Model_Field 

Sample Help Client 


Here is a key with no Help Text, but 
instead a More Help string. 


This is the client's 'Model' field. 

:find_button:** Direct help on Find button. ** 

:done_button 

:More About the Done Button 


Sample Help Client 


This is the client's 'Done' button 


:end of file 
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More Help More Help is used when a single panel (32 lines x 80 characters) of Help Text 

does not suffice. It also allows you to provide a hypertext help facility, if you 
choose to write it. 

When More Help is provided, the Spot Help panel comes up with a button saying 
“More Help”. The user who wants more help clicks the mouse over this button, 
and SunView either finds or tries to start a More Help server. Specifically, Sun- 
View tries to establish an RPC socket link to the More Help server and to pass to 
it the More Help string found after the second colon in the .info file. 

A general More Help server is not provided with SunView 1.80. Programmers 
needing to include More Help in their application(s) must write their own. 

An example is given below that shows how to hook up a More Help server to the 
SunView mechanism. 

Once the server is written, 

1. the server executable must be placed in a directory where it can be found in 
the user’s search path, and 

2. the server’s name must be registered in the /Help/ Server default in the 
Defaults Editor database. 

This allows SunView to find and start the server when a user asks for More Help 
and the server is not running. 

When SunView starts the server, it uses the equivalent of a command like: 

/ --\ 

server defaultjiame More_Help_string 

v_______, 


where 

□ server_default name is the name of the server, and 

□ More_Help_string is the More Help information. SunView would have sent 
this string to the server via RPC but could not because the server was not 
running. So SunView starts the server and sends the string as a command 
line argument. 

As an example, assume the user is running the client program discussed in the 
previous section, with the Help file client. inf o. Also assume a More Help 
server named my_server. 


my_server More_About_the_Panel 

v--- / 

This command line would be produced in the following way: 

1. The user requests Spot Help on the panel. 

2. SunView looks in the .info file, finds the following entry, which has a 
More Help string: 

":panel:More About the Panel” 


t#sun 
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3. So, a More Help button is displayed in the Spot Help panel. 

4. The user clicks over the More Help button. 

5. SunView tries to send the More Help string More_About_the_Panel to 
the More Help server ( my_server ). 

6. The server is not running, so SunView starts it with the command line 
shown. 

You can pass command line arguments to the server by making them part of the 
server default name. For example, having as the /Help/Server default 

m y__ server -flagl 

_ J 


would invoke my_server with flagl as a command line argument, adding 
the appropriate More Help string found in the . inf o file when the user 
requested More Help. In this case, a user wanting More Help about the panel, 
might result in the More Help server being started with a command line like: 



my server 

-flagl 

More About the Panel 

-\ 

l._ 




J 


Once the server is running, it will display More Help for all SunView applica¬ 
tions on demand. 


More Help Functions Three SunView functions support More Help. The first is: 


help rpc register for a More 

Help function 

— 

int 

help rpc register( 
more_helpJune 
) 

void (* 

A 

morejielpJune 


) 0 ; 



l . . 

J 


This registers your server with the help system and causes more help June to be 
called whenever a help request is generated by the help system, morejielp June 
should be of the form: 


( 


void 


morehelpJune 


{request_string) 


char * 


request_string 


/ 

{ 


} 


v 

J 


where request string is a null terminated character string. The character variable 
request string will contain the value more Jielp string that was found with the 
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Spot Help key .info file: 


/- 


:spot_help_key: 


more help_string 


text 


text 


k . . 

J 


This function interprets moreJielp string according to the needs of the applica¬ 
tion. It could use the string as a key for lookup in a file, along the lines of Spot 
Help. Or the string could be interpreted as both a filename and a key. Or, the 
string could be used as a record ID in a database query. 

The second SunView More Help function is: 


help_set more func registers 
the function that gives help on More 

s 

void 

> 

Help 


help_set_more_func ( help_on_helpJune) 




void (* help_on_helpJune) () ; 



k_ 


_ J 


where help on help June is a function similar to the one registered with 
help_rpc_register (), above. It is called when the user asks for help on 
the More Help server itself. In the simplest case, the function that handles Spot 
Help requests on the more Help server can be the same one that was registered 
with help_rpc_register (). 

The last support function unregisters the More Help server. It is good practice to 
use this call when the More Help server completes, to release any RPC sockets it 
used. 


help_rpc_unregister 
deregisters the help function 


f — 


a 


help_rpc_unregister (func) ; 




> 


This function should be called before exiting. 


More Help Example The following program shows how to connect a More Help server to the Spot 

Help mechanism via RPC. When this is done properly, the program will receive 
the More_Help_string from the .info file. 

Use of the More Help string is a What this program does with the More Help string is not particularly exciting; it 
ecision for the application writer. simply makes a panel and displays the string. In more real-life situations, the 

string might be used as a keyword into a file, or as a filename-keyword pair, or it 
might be a record ID for a database query. 
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Note the use of the function calls. 


The help routine registered above, 
is defined here. It simply creates a 
panel and displays the More Help 
string. 


-- 

/* server.c */ 

♦include <stdio.h> 

♦include <suntool/sunview.h> 

♦include <suntool/panel.h> 

♦include <suntool/help.h> 

Panel_item What_I_Got; 

main(argc, argv) 

int argc; 

char **argv; 

{ 

Frame frame; 

Panel panel; 

void server_rpc_in(); 

void server_local_req(); 

frame = window_create(NULL, FRAME, 

FRAME_LABEL , a rgv[0], 

FRAME_ARGS, argc, argv, 

0 ); 

panel = window_create(frame, PANEL, 

WIN_WIDTH, 400, 

WIN_HEIGHT, 100, 

0 ) ; 

What_I_Got = panel_create_item(panel, PANEL_TEXT, 
PANEL_LABEL_STRING, "What I Got Was: ", 
PANEL_VALUE, "", 

0 ); 

window_fit(frame); 

"help_rpc_register(server_rpc_in) H ; 

window_main_loop(frame); 

”help_rpc_unregister(server_rpc_in)"; 

} 

/* RPC handler */ 
static void 
server_rpc_in(request_string) 

char *request_string; 

{ 

panel_set(What_I_Got, PANEL_VALUE , request_string, 0); 
return; 

} 

s.... J 


Help on the More Help Server The following code extends the previous example by showing how to provide 

Spot Help on a More Help server itself. This is done by adding: 

□ HELP_DATA values for the items needing Spot Help, 

□ defining a function to handle Spot Help, 
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□ registering the function with help_set_more_f unc (). 

Notice that in this case the Spot Help function simply turns around and calls the 
same user function that displays More Help. 


Note the addition of help_data; 
the Help Text is in a file named 
server. info. 


Use help_set_more_func to 
define the function to handle Spot 
Help requests on this More Help 
program. 


/* server.c */ 

♦include <stdio.h> 

♦include <suntool/sunview.h> 

♦include <suntool/panel.h> 

♦include <suntool/help.h> 

Panel_item What_I_Got; 

main (argc, argv) 

int argc; 

char **argv; 

{ 

Frame frame; 

Panel panel; 

void server_rpc_in(); 

void server_local_req(); 

frame = window_create(NULL, FRAME, 

F RAME_LAB EL, argv[0] , 

FRAME_ARGS, argc, argv, 

HELP_DATA, "server:frame" , 

0 ); 

panel = window_create(frame, PANEL, 

WIN_WIDTH, 400, 

WIN_HEIGHT, 100, 

HELP_DATA, "server:panel” , 

0) ; 

What_I_Got = panel_create_itern(panel, PANEL_TEXT, 
PANEL_LABEL_STRING, "What_I_Got_Was: ", 
PANEL_VALUE, 

HELP DATA, "server:What_I_Got" , 

0 ); 

window_fit(frame); 
help_rpc_register(server_rpc_in); 

help_set_more_func(server_local_request); 

window_main_loop(frame); 
help_rpc_unregister(server_rpc_in); 

} 
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The help routines registered above, 
are defined here. 


. 

/* RPC handler */ 
static void 

server_rpc__in (request_string) 

char *request_string; 

{ 

panel__set(What_I_Got, PANEL_VALUE , request_string, 0); 
return; 

} 

/* required when user asks for help on server itself */ 
static void 

server_locaI_request(window, request_string, event) 

Window window; 

char *request_string; 

Event *event; 

{ 

server_rpc_in(request_string); 
return; 

} 

V_> 


D.2. Programmable 
Alarms 


SunView 1.80 provides programmable alarms, which “beep” and “flash” at the 
user in a way that is settable from either a C program or from shell commands. 


CAUTION SunView must be installed and be running for the alarms to occur, even 
though you can manipulate the environment variable without SunView. 

A beep is the sounding of the bell on the user’s keyboard. A flash is a color 
reversal in a window; the window frame is repainted with the colors reversed, 
and then painted again normally. 

□ The number of beeps and the number of flashes can be independently set. 

□ There is one setting, however, for the duration of both beeps and flashes, and 
that setting is also the interval between successive beeps/flashes. 

Notethatthe defaultsedit (1) values for SunView/AudibleBell 
and SunView/VisibleBell will determine whether beeps and flashes, 
respectively, occur at all. When an aspect of the alarm is disabled by the indi¬ 
cated default, that aspect will not occur, no matter what the setting of the alarm. 


Shell Command Interface 


SunOS 4.1 provides shell commands to set and get the characteristics of the 
alarm, and to ring it. These commands rely on an environment variable: 


Don’t forget the : (colon) charac¬ 
ters if you try to enter the setting by 
hand. You need them at the begin¬ 
ning, end, and in the middle. 


% set WINDOW_ALARM=:beeps=fr:flashes=/:dur=f; 

#: : where 

# b - number of beeps 

# / = number of flashes 

# t - duration of each beep/flash in milliseconds 

\ _ — - 
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Program Interface 


The setting of this variable can be performed either directly, or through the com¬ 
mand: 

set alarm: [ -b b -f / -d t ] 


where the option arguments correspond to the fields in the environment variable. 

There is a counterpart command that returns the setting, in the form shown 
above: 



This command gets the attributes from WIND0W_ALARM and rings the alarm 
with these attributes. The alarm’s behavior is controlled by the SunView 
defaultsedit (1) entries SunView/Audible_Bell and 
SunView/Visible_Bell, so the sound and flash can be disabled by the user, 
regardless of WIND0W_ALARM. 

set_alarm parses its arguments, encodes them into a termcap ( 3X) -like 
string, and gives to standard output commands to set the environment. The out¬ 
put depends on the value of the S HE LL environment variable. 
- 

#For the C shell: 

set noglob; 

setenv WINDOW_ALARM 'string'; 
unset noglob; 

#For the Bourne shell: 

export WINDOW_ALARM; 

WINDOW_ALARM='string' ; 

i. .> 


As a result of the above, the set_alarm command must be used in a different 
manner than other commands (analogous to t set (1)). For the Bourne shell 
and C shells, use this command to place the result of the call to set_alarm 
into the environment for future reference by the library: 

eval 'set_alarm [options...]' 

With the C-Shell, it may be convenient to make an alias of the form: 

alias alarm 'eval 'set alarm !*'' 


The interface to SunView programmable alarms consists of two calls using the 
win_alarm attribute with the appropriate data structure. 
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Data Structure Shown below is the definition of a simple structure type, Win_alarm (which is 

in window.h). 


/ - 



typedef struct 

alarmval { 


int 

beep_num; 


int 

flash num; 


struct 

timeval beep duration; 


} Win_alarm; 



V 


J 


The values of the structure entries are: 

□ beep_num is how many times to beep, 

□ f lash_num is how many times, to flash. 

□ beep_duration is how long each individual beep/flash lasts. This is also 
the elapsed interval between each successive beep and/or flash. 

Function Calls The following call parses the environment variable window_alarm and returns 

a pointer to the win_aiarm structure. 

- > 

alarm = (Win_alarm *) window_get(window, WIN_ALARM); 

V___ J 


If window_alarm is not set, it returns in the win_aiarm structure the default 
values of: 


t — 

beep_num = 1; 

A 


flash num = 1; 



beep_duration.tv_sec = 1; 
beep duration.tv usee = 0; 


V 


J 


If any of the fields in WlNDOW_ALARM has an illegal value, window_get 
returns the default value for that field in Win_alarm. 

If the duration number is not set and either beep or flash is greater than zero, then 
a default duration of 1 second will be returned in the structure. 

The following beeps the keyboard bell and flashes the window frame. 

window_set(window,WIN_ALARM,&alarm,0) 

If & alarm is NULL, then SunView looks at the environment variable 
window_alarm and uses those values to ring the alarm. Again, if the 
window_alarm environment variable is not set, SunView will use the default 
values. 

Thus, window_set (window, WIN_ALARM, 0, 0) is essentially ringing 
the alarm with the values from the environment variable; it can beep, flash or 
both. 

The alarm’s behavior is controlled by the SunView defaults_edit (1) 
entries SunView/Audible_Bell and SunView/Visible_Bell, so the 
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sound and flash can be disabled by the user, regardless of what the call to 
win_alarm specifies. 


Programmable Alarm 
Example 


This section defines the default 
attributes of the alarm, includes the 
relevant . h files, and defines 
several data structures. 


The following example brings up a SunView window with three text items and a 
button. The text items allow you to specify the characteristics of an alarm, and 
the button allows you to activate it. 


f 



♦include 

<suntool/sunview.h> 


♦include 

<suntool/panel.h> 


♦define 

BEEP ITEM 0 


♦define 

FLASHES ITEM 1 


♦define 

DURATION_ITEM 2 


♦define 

NUMBER_OF_ITEMS 3 


void ring the alarm(); 


Frame 

frame; 


Panel 

panel; 


Panel item 

panel_items[NUMBER_OF_ITEMS]; 


Win_alarm 

example alarm; 


Pixrect * 

rr_button_image; 


v 


J 


This begins the main loop, which 
will create a frame and a panel, and 
define several panel text items. 


r~ ---> 

int 

main() 

{ 

frame = (Frame) window_create( (Frame) NULL, FRAME, 
FRAME__LABEL, "Programmable Alarms Example", 

0 ) ; 

if (frame == (Frame) NULL ){ 

fprintf(stderr, "SunView not available\n"); 
exit(1); 

} 

panel = (Panel) window_create( frame, PANEL, 

0 ) ; 

V_> 


Define the panel text item that 
accepts user input for how many 
beeps. 


- -\ 

panel_items[BEEP_ITEM] = 

(Panel_item) panel_create_item( panel, PANEL_TEXT, 
PANEL_LABEL_STRING, "beeps per alarm :", 

PANE L_VALUE_DISP LAY_LENGTH, 10, 
PANEL_VALUE_STORED_LENGTH, 10, 

PANEL_ITEM_X, 10, 

PANEL_ITEM_Y, 10, 

0 ) ; 

/* check for null pointer */ 

V___, 


Define the panel text item that 


cpsun 
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accepts user input for how many 
flashes. 


Define the panel item to accept user 
input for duration. 


Define the button to actually ring the 
alarm. Notice the callback pro¬ 
cedure, ring_the_alarm, is 
registered here. 


This is the end of the main loop: fit 
everything into the frame, and put it 
on the screen. 
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This is the callback from the button. 
It stores values from the user (if 
any) into the alarm data structure, 
and rings the alarm. 

Notice the window_set call. This 
is where the alarm is actually rung. 


- v 

void 

ring_the_alarm() 

{ 

int duration_in_tenths; 

example_alarm.beep_num = 

(int) atoi( 

panel_get(panel_items[BEEP__ITEM], PANEL_VALUE)); 

example_alarm.flash_num = 

(int) atoi( 

panel_get(panel_items[FLASHES_ITEM], PANEL_VALUE)); 

duration_in_tenths = 

(int) atoi( 

panel_get(panel_items[DURATION_ITEM ], PANEL_VALUE)); 

example__alarm. beep_duration. tv_usec 
= (duration_in_tenths % 10) * 100000; 

example_alarm.beep_duration.tv_sec 
= (duration_in_tenths / 10); 

window_set(frame, WIN_ALARM, & example_alarm, 0); 

} 

v_ J 


Programmable Alarms with 
Help 


We need to include help.h. 


We also define a macro to use in 
entering help_data. 


Finally, consider the following code, which adds Spot Help to the programmable 
alarms example above. 


/ - 



♦include 

<suntool/sunview.h> 


♦include 

<suntool/panel.h> 


#include <suntool/help.h> 


♦define 

BEEP ITEM 0 


♦define 

FLASHES ITEM 1 


♦define 

DURATION ITEM 2 


♦define 

NUMBER_OF_ITEMS 3 


#define 

P ALARM HELP(x) HELP DATA, H p_alarms:x" 


void 

ring_the alarm(); 


Frame 

frame; 


Panel 

panel; 


Panel_item 

panel_i terns [NUMBER OF ITEMS]; 


Win alarm 

example alarm; 


Pixrect * 

rr_button_image; 


l_ 


-j 


This example uses a macro, p_alarm_help to specify the help_data that 
Spot Help will use. 
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Note the p_alarms field in the macro; this directs Spot Help to look in a file 
named p_alarms. info in the help directory defined in the defaults database 
by Defaults Editor. 

The other field in the macro, x, is a variable that is replaced with the key that 
Spot Help used to find the actual text in the file. 


In the main loop we use the 
p_alarm_help macro to indicate 
that we want to add help for the 
frame and the panel. 

This directs Spot Help to the entries 
: frame and : panel in the 
p_alarms. info file. 


-. 

int 

main () 

{ 

frame = (Frame) window_create( NULL, FRAME, 

FRAME_LABEL, "Programmable Alarms Example", 

PAL ARMHELP(frame), 

0 ) ; 

if (frame == (Frame) NULL ){ 

fprintf(stderr, "SunView not available\n"); 
exit(1); 

} 

panel = (Panel) window_create( frame, PANEL, 

P_ALARM HELP(panel), 

0 ) ; 

/* check for null pointer */ 

s._> 


Here we add help for each panel 
text item the user can enter, as well 
as the button. 

The use of the macro is the same 
as in the previous figure. 


r 


panel__items [BEEP_ITEM] = 

(Panel_item) panel_create_item( 

panel, PANEL_TEXT, 


PANEL_LABEL_STRING, 

"beeps per alarm :", 

PANEL VALUE DISPLAY LENGTH, 10, 

PANEL_VALUE STORED_LENGTH, 10, 

PANEL ITEM X, 

10, 

PANEL ITEM Y, 

10, 

P ALARM HELP(beeps), 


0 ) ; 


/* check for null pointer 

*/ 

panel_items[FLASHES_ITEM] 

= 

(Panel_item) panel_create_item( 

panel, PANEL_TEXT, 


PANEL_LABEL_STRING, 

"flashes per alarm:". 

PANEL VALUE_DISPLAY_LENGTH, 10, 

PANEL_VALUE_STORED_LENGTH , 10, 

PANEL ITEM X, 

10, 

PANEL ITEM Y, 

35, 

P_ALARM HELP(flashes), 
n \ • 


/* check for null pointer 

*/ 

v_ 
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More panel items 


panel_items [DURATION_ITEM] = 

(Panel_item) panel_create_item( 
panel, PANELJTEXT, 

PANEL_LABEL_STRING, "duration (sec/10):", 

PANEL_VALUE_DISPLAY_LENGTH, 10, 
PANEL_VALUE_STORED_LENGTH, 10, 

PANE L_ITEM_X, 10, 

PANE L_ITEM_Y, 60, 

PAL ARM_HELP(duration), 

0 ) ; 

/* check for null pointer */ 

rr_button_image = (Pixrect *) panel_button_image(panel, 
"Rock and Roll", 

0 , 

0 ) ; 


panel_create_item 

(panel, PANEL_BUTTON, 
PANE L_ITEM_X, 
PANEL_ITEM_Y, 
PANEL_NOTIFY_PROC, 
PANEL LABEL IMAGE, 


60, 

85, 

ring_t he_a1a rm, 
rr_button_image, 


P_ALARM_HELP(rock_and_roII_button), 

0 ) ; 



Revision A of March 27,1990 





24 SunView 1.80 Update 


Nothing needs to be added to the 
end of the main loop or to the call¬ 
back. 


-- 

window_fit(panel); 

window_fit (frame) ; 

window_main_loop(frame); 

exit(0); 

} 

void 

ring_the_alarm () 

{ 

int duration_in_tenths; 

example_alarm.beep_num = (int) atoi( 

panel_get(panel_items[BEEP_ITEM], PANEL_VALUE)); 

example_alarm.flash_num = (int) atoi( 

panel_get(panel_items[FLASHES_ITEM], PANEL_VALUE)); 

duration_in_tenths = (int) atoi( 

panel_get(panel_items[DURATION_ITEM], PANEL_VALUE)); 

example_alarm. beep_duration.tv_usec 
= (duration_in_tenths % 10) * 100000; 

example_alarm.beep_duration.tv_sec 
= (duration_in_tenths / 10); 

window_set(frame, WIN_ALARM f & example_alarm, 0); 

} 

s__ . _■> 


Now, let’s look at the file containing the Spot Help text. 
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the frame, 


the panel, 


the beeps panel text item, 


-— > 

: f r ame 

Help for Programmable Alarms: frame 
:panel 

Help for Programmable Alarms panel 

This program illustrates the use of programmable alarms, 
new with SunOS 4.1. They allow SunView programmers 
to set the number of bells per alarm, the duration of the 
bell, and whether each bell is audible, visible, or both. 

This tool contains three text items to set the 
parameters of the alarm, and a button that rings it. 

:beeps 

Help for Programmable Alarms: beeps 

Enter an integer into this text item to control 
how many times the alarm beeps. If you don't 
hear a beep, use the default editor to make 
sure that the audible bell is enabled. 

S._> 


Next, we have the flashes panel text 
item, 

r --- 

:flashes 

Help for Programmable Alarms: flashes 

\ 


Enter an integer into this text item to control 
how many times the alarm flashes. If you don't 
see a flash, use the default editor to make 
sure that the visible bell is enabled. 


the duration panel text item, 

:duration 

Help for Programmable Alarms: duration 



This text item controls the duration of each 
flash/beep of the alarm. The units are tenths 
of a second. Enter an integer! Non-zero! 


the rock & roll button, 

:rock_and_roll_button 

Help for Programmable Alarms: rock and roll button 



Hit this button to see and hear what your settings 
do to the beeps, flashes, and duration. 


and the end of the file. 

: end__of_f ile 
k 
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D.3. Colored Panel Items SunView 1.80 offers the PANEL_ITEM_COLOR attribute to support colored panel 

items. Its use is simple: 


r 

-\ 

PANEL_ITEM_COLOR, color, 


V_ 

J 


The color should be given as an index into a colormap, such as is found in 
sunwindow/cms rainbow.h. 


Color Panel Example 


In this example, a frame and panel are created with a variety of colored panel 
items. 


Include the colormap header file. 
The main loop. 


cms_rainbowsetup () is a macro 
defined in cms rainbow.h. 


Set and name the colormap. 


♦include <stdio.h> 

♦include <suntool/sunview.h> 
♦include <suntool/panel.h> 

#include <sunwindow/cms rainbow.h> 


Frame 

Panel 

Panel_item 

Panel_item 

Panel_item 

Pixwin 

u_char 

Pixrect * 


frame; 

panel; 

orange_button, red_choice, indigo_toggle; 
indigo_toggle, green_message; 
green_message, blue_text, violet_slider; 
*pw; 

red[8], blue[8], green[8]; 
button_image; 


main{) 

{ 

frame = (Frame) window_create(NULL,FRAME, 0); 
if (frame == (Frame) NULL ) { 

fprintf(stderr, "SunView not available\n"); 
exit(1); 

} 

panel = (Panel) window_create(frame,PANEL, 0); 
/* check for null pointer */ 


cms_rainbowsetup(red,green,blue); 

pw = (Pixwin *) window_get(panel,WIN_PIXWIN); 

pw_setcmsname(pw,"colorpanel") ; 
pw_jputcolormap(pw,0,8,red,green,blue); 
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Now add an orange button panel 
item, 


button__image = (Pixrect *) panel_button_image ( 
panel,"Orange",0, 0); 

orange_button = (Panel_item) panel_create_item ( 
panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, button_image, 

PANELITEMCOLOR, ORANGE, 

PANE L_ITEM_Y, ATTR_ROW(3), 

PANEL__I TEM_X, ATTR_COL ( 0) , 

0); 

/* check for null pointer */ 

v_ ) 


a multiple choice in red, 


— 

red_choice = (Panel_item) panel_create_item< 
panel, PANEL_CHOICE, 

PANEL__LABEL_STRING, "Red Choice", 

PANEL_CHOICE_STRINGS, "one", "two", "three", 0, 

PANEL ITEM COLOR, RED, 

PANE L_I TEM_Y, ATTR_ROW(5), 

P ANE L_ITEM_X, ATTR_COL(0) , 

0 ) ; 

/* check for null pointer */ 

^ _ > 


display a message in green, 


- 

green_message = (Panel_item) panel_create_item ( 
panel, PANELJMESSAGE, 

PANEL_LABEL_STRING, "This is a Green message", 

PANELITEMCOLOR, GREEN, 

PANEL_ITEM_Y, ATTR_ROW(7), 

PANE L_ITEM_X, ATTR_COL(0), 

0 ) ; 

/* check for null pointer */ 

v___, 


some blue panel text, 


blue_text = (Panel_item) panel_create_item( 
panel, PANEL_TEXT, 

PANEL_LABEL_STRING, "Color: ", 

PANE L_VALUE, "Blue", 

PANEL ITEM COLOR, BLUE, 

PANE L_ITEM_Y, ATTR_ROW (9), 

PANE L_ITEM_X, ATTR_COL(0), 

0 ); 

/* check for null pointer */ 
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a toggle in indigo, 


-- 

indigo_toggle = (Panel_item) panel_create_item( 
panel, PANEL_TOGGLE, 

PANEL_LABEL_STRING, "Indigo Toggle", 
PANEL_CHOICE_STRINGS, "one", "two", "three", 0, 
PANELITEMCOLOR, INDIGO, 

P ANE L_ITEM_Y, ATTR_ROW(11), 

P ANE L_ITEM_X, ATTR_COL(0), 

0 ); 

/* check for null pointer */ 

v_ J 


and finally, a violet slider. 


The end of the program 


-. 

violet_slider = (Panel_item) panel_create_item ( 
panel, PANEL_SLIDER, 

PANEL_LABEL_STRING, "Violet Slider", 

PANE L_MIN_VALUE, 0, 

PANEL_MAX_VALUE, 10, 

PANEL_VALUE, 5, 

PANEL ITEM COLOR, VIOLET, 

PANEL_ITEM_Y, ATTR_ROW(13), 

PANE L_ITEM_X, ATTR_COL(0) , 

0 ); 

/* check for null pointer */ 

window_main__loop (frame) ; 
exit (0); 

} 

S._____ * 


D.4. 24 Bit Color The CG8 and CG9 frame buffers provide 24-bit true color, supported by the Pix- 

rect and SunViewl libraries. This section describes the CG9 hardware and how 
it differs from previous Sun frame buffers. The subsequent sections explain how 
these differences are seen by an application programmer, and address compatibil¬ 
ity issues with existing applications. 

Additional Documentation When reading this section, it may be useful to have read, or have available, the 

following manuals: 

□ Pixrect Reference Manual, for a detailed discussion of plane groups, 

□ SunOS Command Reference Manual, for shelltool and cmdtool, 

□ SunView 1 Programmer’s Guide, for ttysw, text sw, and panels, 

□ CG9 Release Notes, for more specific information on the hardware. 
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Plane Groups Like the CG4, the CG8 and the CG9 have three plane groups. There is a color 

plane group, which for the CG8 and the CG9 is 24-bits per pixel, and there is a 
monochrome overlay plane group with an associated overlay-enable plane group. 
The overlay is provided for fast monochrome performance of text windows. 

The CG8 and the CG9 have an enhanced overlay/overlay-enable implementation 
compared to the CG4. A zero in the CG4 overlay-enable causes the 8-bit plane 
group value for that pixel to be displayed rather than the overlay 1-bit value. The 
CG8 and CG9 requires both the overlay-enable and the overlay planes be zero to 
show the 24-bit color plane group value. The CG8 and CG9 thereby allow three 
overlay colors rather than the two available with the CG4. The two implementa¬ 
tions are compared in the following table. 

Table D-l Enable!Overlay Planes for CG4 and CG8ICG9 


Overlay 

Plane 

Enable 

Plane 

CG4 

CG8ICG9 

0 

0 

8-bit color 

24-bit color 

0 

1 

color 0 

color 1 

1 

0 

8-bit color 

color 2 

1 

1 

color 1 

color 3 


Colormaps: Index Color vs. Sun color frame buffers display at each pixel a 24-bit color value, defined by 8- 

True Color Frame Buffers bits (256 shades) of each of red, green, and blue. This yields 16.7 million dif¬ 

ferent possible colors (2 24 ). However, previous frame buffers limit the number of 
different 24-bit colors that can be shown simultaneously. 

The CG4 column of Table A-l refers to 8-bit color, color 0, and color 1. The 8- 
bit color value that is stored in the frame buffer’s memory is actually an index 
into a color lookup table of 256 entries of 24-bit color values. For example, a 
pixel value of zero indicates to the frame buffer to display the 24-bit value con¬ 
tained at entry zero of the color lookup table. Additionally, the overlay has a two 
entry color lookup table associated with it. 

The entries color 0 and color 1 in the table refer to 24-bit colors in the overlay 
color lookup table. Because different applications may desire a different set of 
colors selected from the 16.7 million different colors, methods for colormap 
changing, sharing, and swapping have been required. (See pr_put colormap 
in the Pixrect Reference Manual, and pw_setcmsname and 
pw_put colormap in the SunView Programmer’s Guide.) 

The CG8 and CG9 are true color framebuffers. Each pixel located in the CG9 
frame buffer’s memory can hold an entire 24-bit color value. Therefore, index¬ 
ing is not necessary and, although the CG9 has a colormap, it serves a different 
purpose. The CG9 colormap has 256 entries for each of red, green, and blue. 
These entries are changed only for gamma-correction of a color monitor. 

Because pr_putcolormap and pw_put colormap are frequently used in 
existing software, the semantics of these functions have been left intact and are 
ignored by the CG9 with regard to the actual hardware color lookup tables. 
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However, recognizing that application programs might want to change the 
hardware color lookup tables, pr_putlut and pr_getlut commands have 
been created (lut is an abbreviation of look-up table). Likewise, the colormap 
commands have had a specific meaning to the overlay plane group and this 
meaning is unchanged, although the CG9 has three colors rather than two in its 
overlay. pr_putlut and pr_getlut provide the new semantics in this case 
as well. The CG9 Release Notes , Chapter 2 gives the differences among 
pr_putcolormap, pr_getcolormap, pr_putlut, and pr_getlut. 

D.5. Double Buffering Another hardware feature of the CG9 is double buffering. (It is the double buf¬ 

fered version of the CG8. ) Some CG3 and all CG5 frame buffers have two 
copies of the color frame buffer to allow double buffering. An application can 
write to one or both buffers while displaying the other, allowing for smooth ani¬ 
mation because the viewer does not see the graphics creation. In the case of the 
CG3 and CG5, both frame buffers are 8-bits deep and independently fit the same 
8-bit scheme. The CG9 accomplishes double buffering by splitting a 24-bit pixel 
into two 12-bit pixels. The application programmer reads and writes to each of 
the double buffers as if they were 24-bit, but the CG9 hardware thresholds the 
color by storing only the high-order nibble of each of red, green, and blue. 

While in double-buffer mode, an application may not read the same value back 
from the double buffer that was written to it. 


canvas_color2 4 Attribute 
and Compatibility 


Very little of the SunView API has changed; there is a new attribute: 


r - 


CANVAS__COLOR2 4 , TRUE 

^ . 

J 


This section explains the aspects of programming the CG9 and CG8 for the Sun- 
View application programmer. 

A SunView application canvas defaults to monochrome unless a 

pw_put colormap call is made to create an 8-bit canvas. This model is true 

for the CG9 with slight variation. First, a new attribute has been added called 
canvas_color2 4 , which is set TRUE if the application wants to use true color 
32-bit XBGR in the canvas. In this situation, all functions such as pw__rop and 
pw_vector work on 32-bit values in XBGR* format. 

If the canvas_color24 attribute is not set and a pw_put colormap call is not 
made, then the canvas defaults to the monochrome overlay. 


In XGBR format, a 32-bit word is divided into four channels of 8 bits each. The X channel (the high-order 8 
bits) is currently undefined and reserved for future enhancements. The next channel contains 8 bits for the blue 
color component. The other two channels hold corresponding information for the green and red components. 
The three components index the red, green, and blue portions of a look-up table, giving RGB components which 
combine to produce a particular hue and intensity that is seen on the screen. 
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8-Bit Color Mode If a pw_put colormap call is made, the canvas is placed in the 24-bit plane 

group but uses 8-bit indexed operations. In this situation, all functions such as 
pw_rop and pw_vector work on 8-bit indexed color values but display the 
appropriate 24-bit value. There are a few cautions associated with this mode of 
operation. One is that the actual depth of the canvas is 32-bits deep so operations 
to a memory pixrect have the same limitations as described in Table A-2 below. 
The standard rop operations between pixrects of different depths are allowed to 
some extent, as summarized in the table below. 

Table D-2 rop Operations (Limitations) 


Operation 

Allowed? 

0 


n 

yes 

1 

—> 

n 

yes 

n 

— > 

n 

yes 

n 

-» 

1 

no 

24 

—> 

32 

no 

32 

— > 

24 

no 


The value n can be 1, 8, or 32, but not 24 (bits). Note that 8-to-32 bit and 32-to-8 
bit are not supported. To translate pixel colors between 8 and 32, use the formula 
shown below. This format uses the 8-bit pixel value (the variable color 8) with 
the 8-bit colormap to generate a 24-bit color, which is saved in the integer vari¬ 
able color24. This color24 variable has its true color stored in XBGR for¬ 
mat. The value can then be saved as a 32-bit pixel in the pixrect’s 
pixPG_24BiT_C0L0Rplane group. 


-- 

int color24; 

unsigned char red[256],green[256],blue[256]; 
color24 = red[color8] + 

(green[color8] << 8) + (blue[color8] « 16); 

V_____ y 


Summary of 24 Bit Color Usage The use of this attribute is summarized below. 
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Table D-3 Color Attribute Usage Summary 


Effect 

SunView Attributes 

mono 

window_create() 

8-bit indexed emulation 

window_create() 

pw_putcolormap 


or 


window_create( CANVAS_COLOR24, TRUE) 
pw_putcolormap 

24-bit 

window_create( CANVAS_COLOR24 , TRUE) 


Memory Pixrects You can create 24-bit memory pixrects, which may be useful for synthesizing 

images that are later displayed. 

It can be more efficient to use a 24-bit memory pixrect first to generate an image, 
and then to save that image as a 24-bit rasterfile. When pr_load () is called to 
load a 24-bit rasterfile, however, it automatically loads it as a 32-bit pixrect so 
that Pixrect operations run more efficiently. When pr_dump () is called, the 
converted pixrect is saved in a 32-bit rasterfile. 

Another caution is that double buffering uses 24-bit to 12-bit thresholding, which 
tends to confuse the 8-bit indexed mode. Thus, double buffering is not supported 
in 8-bit indexed mode. Furthermore, because of the differences in hardware 
colormaps between 8-bit frame buffers and 24-bit frame buffers, colormap ani¬ 
mation is also not supported. 


No double buffering in 8-bit indexed 
mode. 


Avoid duplicate colormap values in 
8-bit indexed mode. 


One final caution associated with 8-bit indexed mode is related to redundant 
colormap entries. If the application has multiple index entries with the same 24- 
bit color value, then some operations may fail because the wrong index might be 
used. This is easily overcome through minor changes to the colormap values. 

When writing application programs, make sure that all entries in the colormap 
are unique. This action guarantees that reverse indexing from a true-colored 
pixel value back to the index value is correct. If several entries must share the 
same color, these entries can vary slightly on the lower bits, which typically does 
not result in any visual difference. For example, if four entries must have the 
same color of (255, 0, 155), do not initialize the colormap like this: 


— 

NOT THIS WAY 

struct color 

[unsigned char r, g, b; } cmap[] = { 

> 

{ 255, 

o. 

155, } 


{ 255, 

0, 

155, } 


{ 255, 

0, 

155, } 


{ 255, 

0, 

155,}}; 


V_ 



_ J 
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Transparent Overlay 


Instead, initialize the colormap as follows: 


r 




X 

THIS WAY 





struct color 

(unsigned char r, g, b; 

} cmap[] = { 


{ 255, 

o. 

155, } 



{ 255, 


155, } 



{ 255, 

o, 

156, } 



{ 256, 

Or 

155, } }; 



v_ 




_/ 


A new feature associated with the CG9 is the ability to switch to the overlay 
plane or the overlay-enable plane from a color canvas, which allows quick 
rendering of text or graphics over the canvas without disrupting the underlying 
24-bit image. This action is accomplished through a new Pixwin, call 
pw_set_planes_direct ly. This function takes three parameters: 

1. The Pixwin pointer to the Pixwin of the canvas. 

2. The plane group to which you wish to change. 

3. The planemask associated with the new plane group. 

Special caution should be taken to use pw_lock and pw_unlock around this 
code. Also, always restore the canvas to its original state before unlocking. 

An example of the use of pw_set_planes_directly follows: 


/-\ 

int plane_group_save, planes_save; 

/* Pixrect *pw from canvas, be sure to call pw__lock */ 

/* save old state of canvas */ 

plane_group_save = pr__get_plane_group (pw->pw_pixrect) ; 

(void) pr_getattributes(pw->pw_pixrect, & planes_save)/ 
pw_set_planes_directly(pw,PIXPG_OVERLAY,1); 

/* all pw functions now affect the overlay on the canvas */ 
/* restore old state of canvas before unlocking */ 

pw_set_planes_directly(pw, plane_group_save, planes_save); 

/* unlock the pw region */ 

v---, 

Note that the overlay-enable plane has a different definition than that for the 
CG4. The overlay colors in the overlay colormap shown in CG9 Release Notes, 
Chapter 1 are set by SunView as follows: 
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Table D-4 SunView Overlay Colors 


Overlay 

Overlay Enable 

Color 

0 

0 

24-bit value 

0 

1 

Window System Background Color 

1 

0 

Window Foreground Color 

1 

1 

Window System Foreground Color 


The " 1 0" color is set to the foreground color in order to have the cursor show up 
as the correct color over the canvas. 

When using this feature be aware of the following: 

□ Always use p w_l ock(unlock) when alternating between plane groups. 

□ Always return to the real canvas plane group before unlocking. 

a SunView knows only about the real plane group of the canvas. Therefore, 
the overlay planes cannot be retained or redisplayed by SunView. Repairing 
damaged canvases is the responsibility of the application programmer. 

□ Since the cursor is the same color as the overlay foreground, it may disap¬ 
pear in regions filled with that color. 

□ Do not call pr_putlut from a Pixwin application. If you change the 
overlay colormap through a pr_putlut command in a Pixwin application, 
all overlay windows flash to the new color and the windowing system keeps 
restoring the real colors. 

Cursor Unlike the CG4, with the CG8 and the CG9, the cursor is always in the overlay. 

Therefore, all cursor rop operations, such as exclusive OR’s, are performed in 
the overlay plane and never in the 24-bit color plane. 

Command Line Options Unlike the CG4, neither the CG8 nor the CG9, supports access to the mono¬ 

chrome overlay and the 24-bit color plane as two distinct desktops. Thus the fol¬ 
lowing SunView command line options are disabled. 

Figure D-1 Disabled SunView Flags 


f . - . ■ 

. ..x 

DISABLED - do not use with CG8 or CG9 


%sunview -8bit_color_only 


%sunview -overlay_only 


%sunview -toggle_enable 


l... :: 

J 


Text subwindows in SunView tools such as shelltool, cmdtool, and 
text edit have command line arguments that allow you to specify a fore¬ 
ground and background color for a window. These command line options are as 
follows: 


r 


A 


-Wf r g b -Wb r g b -Wg 


k 


J 
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(See sunview(l) in the SunOS Command Reference Manual for a definition of 
these options.) The CG9 (unlike the CG8), supports all of these options, but per¬ 
formance declines when using -Wg, since every pixel of every character in the 
window requires 32-bit operation, instead of the 1-bit operation required if the 
window remained in the overlay. 

D.6. Keyboard Support A number of questions have arisen about the usage of the . text swr c file. 

These are addressed here. 

There are 15 keys on the right hand side (the keypad) that can have functions 
assigned to them. Each key can be named: 

KEY_RIGHT (n) where 15 > n > 1 
R (n) 

Rn 

Similarly, the top function keys each have three names: 

KEY_TOP (n) where 12 > n > 1 

F (n) 

Fn 

The functions assigned to the keys are constructed from filters. When a function 
key is pressed with a text selection, the selected text is piped through the filter 
assigned to that key. The output is then piped back into the text at the carat. (If 
the selection was pending-delete, the original text is removed.) 

There are a number of special filters, documented in 

textedit_f ilter s (1), that are provided especially for SunView users. 

□ insert_brackets, 

□ remove_brackets, 

□ align_equals, 

□ shift_lines. 

Note, however, that any reasonable combination of shell commands can be used 
as a text subwindow filter. 


A function is assigned to one of these keys by including in the . textswrc file 
a statement like: 


f 



/* 



* Note that: 



* insert brackets 

/* */ does NOT work 


*/ 



KEY_TOP(10) FILTER 



insert brackets "/* 

ii H * j n 


V_ 


j 


This example shows how to include C language comment markers around a piece 
of text. You would enter this snippet into your . textswrc file, and save the 
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For trof f italics 


Several trof f command pairs, 
each on its own line 


file. Then bring up a new textedit tool, since the changes only become effec¬ 
tive when a tool is started. Then, select the text pending-delete, and press the 
key. The text will be replaced with a copy of itself surrounded with “/* ” and 
“*/”. Note the C-like syntax of comments in . texts wrc. 


The following example does the same thing, by entering the octal value for char¬ 
acters in the desired string. 


— 

KEY__TOP (10) FILTER 

insert brackets "\057*\040" "\040*\057" 

s._ 

-\ 

_/ 

You might want to add a filter to remove comments: 

/- 

KEY_TOP(10) FILTER 
remove brackets ”/* " " */" 


k _ 

_ J 

Several filters shown below are handy for trof f users. 

r - 

R(1) FILTER 

insert brackets "\fl" "\fP" 

KEY_TOP(12) FILTER 

insert brackets ".BS\n.LS\n" "\n.LE\n.BE" 


V _ 

J 


The next group shows a variety of parentheses and quotes used: 


parentheses, 


quotes. 


-- - > 

/* 

* Note: insert_brackets "(" ")" also works, and 

* insert_brackets ( ) also works 

*/ 

KEY_RIGHT(4) FILTER 

insert_brackets \( \) 

/* 

* Note: insert_brackets "\"" "\"" does NOT work 

*/ 

KEY_RIGHT(5) FILTER 

insert_brackets \" \" 

/* 

* Note: insert_brackets ""\'\ r " does NOT work 
*/ 

KEY_RIGHT(9) FILTER 

insert_brackets \'\' VV 

v___ J 


The final example uses the Is command to obtain the listing of the current direc¬ 
tory and pipe it into the text subwindow after a little formatting. 
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-, 

KEY_TOP(10) FILTER 

Is | i’nsert__brackets ”*List**\n" "*End**" I shift_lines 4 

s_> 


This can be done with awk or sed scripts to great advantage. 


r 

- 

KEY TOP(10) FILTER 


awk -f ~me/mydirectory/myscript 


k_ 



Limits to Assigning Keys 


D.7. Programming Hints 


There are a number of restrictions on the use of function keys in SunView. The 
following keys are not assignable at all: 

□ CEO is CAPS LOCK 

□ (LI 1 is Stop, and also used with in the abort sqeuence. 

Another group of keys cannot be mapped via .text swr c unless you set the 
/ Input/Arrow_Keys default to "No" 

□ Keys IR§ 1 , [R1Q1 , IR121 and 1R141 are the arrow keys; 

□ (R71 is Home , which moves to the beginning of the editing buffer, 

□ (R131 is End, which moves to the end of the editing buffer, and 

□ I Rll I is the function go_line_forward , move to the start of next line. 

The keys on the left keypad are not mapped directly. If the user sets the 
/ Input/Lefthanded default to “Yes”, the SunView functions move from 
the left keypad to the right one, and selected keys assigned to the right keypad 
appear on the left one. 

This section offers tips and techniques that are either not previously mentioned in 
the documentation or that concern how to handle bugs or known problems. 


Memory Leaks From Button A SunView program may fail to reclaim memory after destroying an object. 

Images This loss of useable memory (“ memory leakage”) is cumulative and eventually 

causes the system to crash. To avoid these problems, there are precautions to 
observe. 

A button image is a separate object, and therefore is not destroyed with the but¬ 
ton, (and may be reused, for example, with another button). Thus, the memory 
allocated by panel_button_image () for the panel button image is not 
freed when the panel button is destroyed. 

To avoid this leak, create the button image explicitly, so that it has a handle by 
which it can be destroyed. The examples in Color Panel Example earlier in this 
Appendix show how this is done. 
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Counting File Descriptors 


File Descriptor Leakage 


Null Pointers 


pixwin and pixrect 


SunView makes heavy use of file descriptors, one result of which is that it is 
often useful to know how many file descriptors are open. This can be accom¬ 
plished with the f stat (2) system call. The method is to loop over each pos¬ 
sible f d, explicitly checking its status with f st at (2). 

The question of the upper limit of the loop can be answered either by choosing a 
suitable number such as 256, or more dynamically by using the get dta- 
blesize (2) system call to determine the limit. 

An example appears in the Kernel Interface chapter of the System Services Over¬ 
view. 

window return does not destroy the windows in addition to exiting from 
window_loop. 

Some programmers may not realize that window_return exits from 
window_loop, but does not destroy any windows. As a result the file descrip¬ 
tors associated with the windows remain in use and unavailable for other win¬ 
dows. To reclaim those file descriptors, be sure to call window_destroy. 

Failure to use window_destroy, will cause error messages such as: 
-. 

pr_open: open failed for /dev/fb 

no more windows available 

WIN ioctl number lc: Too many open files 

window: Window creation failed to get new fd 

/dev/win49 would not open (be created)(errno = 24) 

no more windows available 

WIN ioctl number lc: Too many open files 
window: Window creation failed to get new fd 
Segmentation fault (core dumped) 

V._ J 


Problems can arise when a SunView function call to create an object (frame, 
panel, or panel_item for example) returns NULL. You cannot blindly use such a 
pointer without first checking whether it is NULL. Although it is common prac¬ 
tice not to check pointers, and usually does not create problems, it is careless pro¬ 
gramming and can lead to trouble. 

The examples in this Update Appendix check for NULL pointers when creating 
base frames, and indicate by comments when to do so after the creation of other 
objects. 

You are advised to adopt this practice in your own SunView code (and elsewhere 
too). 

Pixwin calls (pw_*) offer a higher level of functionality than pixrect (pr_*) 
calls, and thus should be used whenever possible. Sometimes it happens that 
pixwin does not offer necessary functionality. In such cases, the pixrect interface 
is available, as defined in the documentation. However, the pixrect interface is 
more likely to change in the future than is pixwin. Moreover, undocumented 
calls are not supported, and should not be used. 
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Limitations of 

icon_load__mpr () 


Hardware for Multiple 
Desktops 


The present default settings for the file format parameters of icons are: 
Format_version = 1 

Width = 64, 

Height = 64, 

Depth = 1, 

Valid_bits_per_item = 16. 

These values are currently subject to the following limitations: 
Format_version must always be 1. 

Width must be a multiple of 16. 

Depth must always be 1. 

Valid_bit s_per_item can only be 16 or 32. 

To run multiple desktops on a single screen, the user needs a CG4 framebuffer 
(10 bit planes). 


ws_set_f avor Default The ws_set_f avor flag controls whether or not the window driver will try to 

Value Changed To 0. boost the priority of the window process (and its children) that has the current 

event lock. The default is 0. In very tight memory situations, setting this to 1 will 
improve interactive performance. 


textsw_wraparound_s iz e The attribute textsw_wraparound_size in the text subwindow package is 

attribute not documented. It is of type int and specifies the maximum allowed size (in 

bytes) of the edit log file (in /tmp) associated with a text subwindow. The 
lower bound of this attribute is 8096, which is silently enforced. The default 
value is textsw infinity (allow the edit log file to grow as much as needed). 

not if y_f lush_pending notif y_f lush_pending removes (flushes) all pending events for a client. 

If you call it after doing a window_destroy, the destroy event is removed 
and the window will not be removed at all. 


Interposing Scroll Handlers When trying to interpose your own scroll handler, do not use 

scrollbar_scroll_to in the interposed routine, as it causes an infinite 
loop by generating another scroll event. The proper approach is to have the inter¬ 
posed routine either set a flag, set a timer, or generate a secondary non-scrolling 
event to be processed outside of the event handling pipeline. 

Additional auto_sigbits The following bits in sigbites_jptr should be noted by those writing their 

own prioritizers: 

□ SIGTSTP means notif y_destroy should be called with status of 
DESTROY_CHECKING. 

□ SIGTERM means benotif y_destroyshould of DESTROY_CLEANUP . 
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□ SIGKILL means notify_destroy should be called with status of 

DESTROY_PROCESS_DEATH. 

FBIONREAD There is no FBIONREAD SunView function; references to it result from a typo¬ 

graphical error in the name of the correct call, FIONREAD. 


FRAME_SHADOW and Programs using FRAME_SHADOW instead of FRAME_SHOW_SHADOW to set or 

FRAME_SHOW_SHADOW inhibit a shadow, will create an error message but continue execution. All 
incorrectly documented sub windows will have shadows. 


not all pixwin functions are 
documented 


SCROLL NORMALIZE 
attribute 


Not all the pixwin functions in /usr/include/sunwindow/pixwin. h are 
documented in either the SunView Programmer s Guide or the SunView System 
Programmer s Guide. Undocumented calls are not supported and are subject to 
change without notice. 

The default for SCROLL_NORMALIZE is TRUE. When scrollbars are used 
within panels, the default behavior is to scroll to the first line in view for a panel 
item. This can sometimes cause problems when trying to view a panel item, such 
as a choice item layed out vertically, since all PANEL__CHOICE_STRINGS 
may not be visible within the scroll region and cannot be scrolled into view 
because SCROLL_NORMALIZE is TRUE. In those instances set 
SCROLL_NORMALIZE to FALSE, in addition to setting the scrollbar’s 
SCROLL_LINE_HEIGHT. For example: 
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Subframes Cannot Be 
Iconified 


tinclude <suntool/sunview.h> 
#include <suntool/panel.h> 
#include <suntool/scrollbar.h> 


Frame 
Panel 

Panel_item 
static int 
Scrollbar 
main(argc,argv) 
int argc; 

char **argv; 


f rame; 
panel; 

choice_item; 
choice_count = 0; 
sb; 


{ 

frame = window__create (NULL, FRAME, 

0 ); 

sb = scrollbar_create(SCROLL_NORMALIZE, 
SCROLL_LINE_HEIGHT, 5, 

0 ), 

panel = window_create(frame,PANEL, 


FALSE, 


WIN_ROWS, 5, 

WIN_VERTICAL_SCROLLBAR, sb, 

0 ); 

choice_item = panel_create_item(panel,PANEL_CHOICE, 
PANEL_LABEL_STRING, "Choices:", 

PANEL_LAYOUT, PANE L_VERTICAL, 

PANEL_CHOICE_STRINGS, 


"01", 

"02", 

"03 

"04", 

"05", 

"06 

"07", 

CO 

o 

"09 

"10", 

"11", 

"12 

"13", 

"14", 

"15 


0 , 

0 ); 

window_fit_height(frame); 
window_main_loop(frame); 

} 


Subframes (not subwindows, but frames created by calling window_create ( 
basef rame, FRAME) ) cannot be iconified. All subframes are intended to be 
transient and are not allowed to close to an icon. 


FRAME INHERIT COLOR If you set the FRAME_INHERIT_COLORS attribute to TRUE for subwindows 
behavior before setting up a colormap for the frame, the subwindows will not inherit the 

colors of the frame. The correct procedure is to set the attribute after the color- 
map. 
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Destroying A Window 
Without Returning To The 
Notifier 


Using window_create 

without Error Message 


.sunview and Environment 
Variable Expansion 


-. 

THIS WAY 

my_set_colormap_function () ; 

window_set(frame, FRAME_INHERIT_COLORS, TRUE, 0); 

NOT THIS WAY 

window_set(frame, FRAME_INHERIT_COLORS, TRUE, 0); 
my_set_colormap_function(); 

s___> 


The following code shows how to destroy a window without returning to the 
notifier. window_destroy posts to the window a destroy event which won’t 
be processed until the notifier resumes. 

Note that the call to not if y_f lush_j?ending may be necessary to remove 
pending events for the window. 

— 

destroy_subframe(sub_frame) 

/* window_destroy(sub_frame) immediately */ 

Frame sub_frame; 

{ 

if (notify_post_destroy(sub_frame, 

DESTROY_CHECKING, 

NOTIFY_IMMEDIATE) 

!= NOTIFY_DESTROY_VETOED) { 

(void)notify_f lush_pending(sub_frame); 

(void)notify_j?ost_destroy(sub_frame, 

D E S T ROY_C LEANUP, 

NOTIFY_IMMEDIATE) ; 

} 

} 

l_ J 


Occasionally an application will want to call window_create repeatedly and 
yet not have it be apparent to the user when the system runs out of /dev/win 
devices. Either they wish to report the error themselves, or they just want to 
create as many windows as they can without making the user see an error mes¬ 
sage when the limit is reached. 

Currently window_create outputs an error message to standard error when 
there are no more windows and returns NULL. So when the program finds out 
there is an error, the user has already seen the error message. 

Currently, the only way around this is to redirect standard error away from the 
console. 

There are limits on how shell environment variables in the . sunview file are 
expanded. For example, using paths like $PROGDIR/f ile_to_run or 
'user/bin/f ile_to_run does not work. For efficiency, SunView uses a 
simple exec() on each line in the file, so expansion does not occur. This is 
not likely to change in the future. 


f#sun 
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Tools Off Sreen 


pw_put attributes 


However, you can use variables like this if the command line is a call to csh: 


/— , -————-— ----—, 


csh -c $PROGDIR/file to run 


csh -c ~flake/bin/file_to_run 



J 


Sometimes, when tools come up, the bottom edge of the tool will be partially off 
screen. This causes scrolling problems and/or funny characters. The effect of this 
problem can be alleviated by moving the window up so that it does not extend 
over the bottom of the screen. 

pw_put at tributes does not set the attributes of the retained memory pix- 
rect. Also, bitplane masks do not work on a memory pixrect. These capabilities 
are necessary to do plane manipulation, for example, double buffering. 

The following code can be used to create this type of memory pixrect: 

/-\ 

♦include <sys/types.h> 

♦include <pixrect/pixrect.h> 

♦include <pixrect/pr_util.h> 

♦include <pixrect/memvar.h> 

Pixrect * 

mem_create_with_planemask(w, h, depth) 
int w, h depth; 

{ 

Pixrect *pr; 
struct mprp_data *mprd; 
if (pr = mem_create(w, h, depth)) 

if (mprd = alloctype(struct mprp_data)) { 

mprd->mpr = *mpr_d(pr); 
free(mpr_d(pr)); 
pr->pr_data = (caddr_t) mprd; 
mprd->mp r.md_flags |= MP_P LANEMAS K; 
mprd->planes = ~0; 

} 

else { 

pr_destroy(pr); 
pr = 0; 

} 

return pr; 

} 

v—_ 4 


A sample call to this function might look something like this: 
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/* 

* Fixes a retained memory pixrect in a canvas 

* pixwin by replacing it with a memory pixrect 

* which supports attributes. 

*/ 

static void 

fix_retained_pixrect(win,pw) 

Window win; 

Pixwin *pw; 

{ 

Pixrect *pr; 
int w,h,d; 

w = (int)window_get(win,WIN_WIDTH); 
h = (int)window_get(win,WIN_HEIGHT); 
d = 8; 

if ((pr = mem_create_with_planemask(w,h,d)) == NULL) { 

fprintf(stderr,"Could not create memory pixrectO); 
exit (1); 

} 

pr_destroy (pw->pw_prretained) ; 
pw->pw_prretained = pr; 

} 

V_ J 


Filename Completion 


Using the [Esc 1 key to obtain filename completion does not work in SunOS 
release 4.1. 


Sticky Secondary Selections 


Summary of SunView 1.80 
Bug Fixes 


Sunview sometimes gets stuck in secondary selection mode (when things are 
underlined). To correct this, go to a command window and use the 
clear_f unctions command. This should cause the selection service clients 
to give up their selections, thereby clearing the selection service. 

This section consists of a table describing each bug or RFE (Request for 
Enhancement) that has been fixed in SunView 1.80, collated in ascending order 
by the Bug ID number ( Bugid). The Bugid is the “reference number” that is 
assigned to each bug when it is reported, and is used subsequently to refer to it. 


Table D-5 Sunview 1.80 Fixed Bugs 


bugid 

Summary Description 

1002377 

window display lock broken when window exposed 

1002411 

can start suntools when not at display 

1002523 

textedit incorrectly sizes windows with the -Ww flag 

1002759 

a frame created with WIN SHOW TRUE gives WIN ioctl error 

1003340 

unnecessary repaint on upper split view 

1003354 

a blank FILTER entry in . text swrc hangs when key pressed 

1003383 

Prevent multiple inclusion of system include files 

1003571 

icon’s default font not set until display time 

1003581 

window set FRAME CLOSED to TRUE gives "win ioctl" message 
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Table D-5 Sunview 1.80 Fixed Bugs — Continued 


bugid 


1003648 

1003788 

lockscreen does not accept passwords with control characters. 
image_browser_2 takes up (infinite?) CPU time on “Browse” 

1003815 

1003850 

1003877 

1004221 

panel starts interval timer without keyboard focus 

Too large a window number (12 8)! message with two framebuffers 
signal TON while reading from standard input in dbx/scripts 

Inverted suntools do not work on Prism’s b/w framebuffer. 

1004442 

1004580 

1004586 

1004838 

shelltool (and other tools) dump core when $WINDOW_PARENT not set 
textsw_f ile_lines_visible () returns incorrect values 

Multiple colors for panel items 

ttysw uses fork () rather than vf ork () 

1005102 

1005499 

1005729 

1006084 

memory leak in panel_destroy_item () 

tty subwindow goes into infinite loop if open / dev/ttyp ? fails 

WIN_FONT text subwindow attribute ignored 
ttysw children do not exit 

1006159 

1006173 

1006217 

1006222 

cmdtool does not allow Reset immediately after Store 
damaging suntool’s colormaps can cause “panic: bus error” 
suntools does not warn you it’s busy when starting up 
default sedit does not allow setting nosunview 

1006341 

1006426 

1006560 

1006591 

pw_line draws different than pw_vector given same coordinates 
window_create failed to return NULL on failure for panel 

Can not use ~ to specify icon in SunView . rootmenu file 
exit of suntools does not zero out /etc/utmp entries 

1006652 

1007187 

1007442 

1007443 

screenblank dumps core if argument is missing 
shelltool dumps core if given -Wt with no arguments 
rectlist. h needs guard 

PW_DBL_WRITE sets to PW_DBL_FORE when creating menu 

1007620 

1007696 

1008155 

1008199 

screenblank persists despite keyboard activity 
suntool should return windowfd when using lint in llib-1 

Find and Replace loops replacing single occurrence of text 
toggling TTY ARGV fails 

1008457 

1008564 

1008579 

1008849 

panels do not go to back on Shift-L5 

Cutting selected text in subwindow leaves selection on-screen 
textedit scrollbar bubble misplaced for very large files 
faulty SunView program gives “panic: bus error” 

1008949 

1009260 

1009284 

1009354 

cmdtool dumps core after bad option on command line, 
tty windows fail to deallocate old frame icon pixrects 
notify. h uses f d_set but does not include its definition 
resizing window gives bad message 

1009357 

1009507 

1009822 

1010462 

fullscreen resize option available when already fullscreen 

LOC_RGNEXIT missing when scrollbars are south and east 
second ghost caret from mailtool Compose=>Include 
text subwindow still uses old menu_prompt instead of alerts 

1010463 

1010485 

CTRL-tab in a text subwindow does not work after a tab is pressed 

Find=>Selection Forward does not work in mailtool 



sun 
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Table D-5 Sunview 1.80 Fixed Bugs — Continued 


bugid 

Summary Description 

1010522 

1010557 

shift_lines will not shift left 

Save layout uses current directory, not home directory 

1010746 

1010847 

1010972 

1011026 

File=>Load File accelerator works too often 

shift_lines -t -1 broken, also Text=>Extras and . textswrc 

Pull right menu appears .then vanishes mysteriously 
double-buffering and pw text interact badly 

1011042 

1011090 

1011133 

1011234 

MENU GEN PROC creates bogus MENU STRING_ITEM, value pair 

must have a .defaults file 

shift lines requires . indent .pro file 

illegal memory free in suntools 

1011384 

1011412 

1011519 

1011853 

file truncated in text edit upon save with full filesystem 
alert attribute ALERT_BUTTON_YES disables right mouse menu 
suntools hangs with CG3 and GP1 or GP+ 

Exiting suntools without quitting chesstool causes machine to panic 

1011938 

1011973 

1012020 

1012023 

PW DBL EXISTS not defined in <sunwindow/pw dblbuf.h> 

Sun-2 and Sun-3 shared library version numbers are different 
textsw filters drop data 
lockscreen security hole 

1012414 

1012415 

1012448 

1012506 

-Wf flag for tools broken 

cursor not in foreground color 

cat a binary in cmdtool results in a core dump. 

PANEL_ITEM_BOXED in panel.h but not implemented 

1012577 

1012580 

1012587 

1012695 

textsw_insert gets progressively slower in 3.x 
scroll buttons do not work in canvas_demo 
creating a tty after one has been destroyed hangs program 
tools started from SunView sometimes do not appear 

1012757 

1012758 

1012774 

1013745 

tty subwindow calls signal {3) which is illegal in SunView 

ESC[0;7m does not invert in shelltool on 3.x 
menus cause intermittant colormap flashing in 4.0 
in textedit, a Ctrl-Delete enters undeletable character 

1013746 

1013767 

1013901 

1014035 

Get/Put from cmdtool to textedit window can kill cmdtool. 
variable collision causes no cursor in ttysw when using FORTRAN77 
sunview -i and bad root menu file results in all black screen 

8-bit characters not displayed correctly when batching on 

1014075 

1014145 

1014179 

1014194 

monochrome pixwin inheriting colormap of overlying cursor 
window set () should return non-zero value for success, 
textedit dies with SEGV on blink owner 
memory leak everytime a window is destroyed in notifier 

1014751 

1014820 

1014884 

1014935 

arguments to gf xsw_select () defined incorrectly in gf xsw.h 

Incorrect use of select system call in win_bell. c 
changing the monochrome colormap in 4.0 does not work correctly 

Debugging messages in sunwindowdev waste bytes 

1015097 

1015167 

attr. h does not conform to ANSI C standard 

52 menu items gives “menu_show: Menu too large for screen” 
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Table D-5 Sunview 1.80 Fixed Bugs — Continued 


bugid 

Summary Description 

1015181 

1015394 

icon_load_mpr returns incorrect data. 

MENU_REPLACE_ITEM causes memory leak,menu_destroy no effect 

1016307 

1016479 

1016585 

1016660 

attr rc units to_j?ixeIs does not traverse embedded av-lists 

FRAME ICON does not reclaim memory 
cf ramedemo dumps core under 4.0 

attribute header file attr. h uses but does not define caddr_t 

1016718 

1016820 

1016876 

1017411 

RFE for editable panel text items 

ntfy errno abort init never gets set 

The -R usage for SunView libraries is incorrect for 4.0 

8-bit fonts are "eaten" by mouse if written on top of cursor 

1017503 

1017814 

1017887 

1018216 

obsolete directory /usr / lib/ key maps in the distribution tape 
panel will not be displayed correct on machine with GP2 

MENU GEN PROC causes bus error 

win_enumall () procedure causes errors when 128 windows exist 

1018599 

1018720 

1018784 

1018785 

in FrameMaker, F6 and F7 operate incorrectly 
pw_line does not rasterize patterned lines consistently 
cursor color incorrect 

dragging a window off the screen panics the kernel. 

1018963 

1018992 

1019086 

1019256 

problem with ptys being left in bad state 
selection destroys window and leaves tty device in bad state 
pctool: seln Create failed message on 4/330 
macros not defined in values . h 

1019290 

1019359 

1019398 

1019404 

set_cur sor caused a canvas repaint 
cannot get PANEL VALUE FONT of a panel text item 
text edit allows user to create file with whitespace in name 
request for more than 128 windows 

1019664 

1019891 

1019897 

1019907 

SunView: No such file or directory message; missing /dev/* 

SPARC cursor performance problem 

bad cursor image size test in winio getuser cur sor () 

premature crosshair cursor pixrect image data allocation 

1020222 

1020319 

1020397 

1020454 

textsw_reset () does not free memory 

LOC_WINEXIT events are being delivered erroneously 

Too large a window number {128)! message built into kemal 
cmdtool can exit leaving pty in unusable state 

1020719 

1020730 

1021270 

1021476 

window_create of subframe can crash instead of return NULL 
process’s nice value gets zeroed 

escape sequences hang a cmdtool that is remote logged in. 
makefile does not make shelltool or cmdtool target 

1021477 

1021544 

1021664 

1022020 

icon code incompatible with pixrect library 
pw_line does not work with retained, color canvases 
win_getnewwindow () does not always return -1 failure 
shift-L5 does not put windows to the back, and moves others to front 

1022552 

1022841 

suntools -s with nonexistent filename will hang the system, 
the edit log wraparound size has no effect on cmdtool 
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Table D-5 Sunview 1.80 Fixed Bugs — Continued 


bugid 

Summary Description 

1023098 

1025077 

subframe destmction results in 4K memory leak 
cron cannot execute the command lockscreen 

1025689 

1025804 

1025886 

1026368 

Changing fonts in a tty will crash a sunview application 
canvas damage is incorrectly cleared to red 
lockscreen -e should log the user out 

error messages from ttysw_f ork_it () and ttysw_tty_restore () confused 

1026613 

1026708 

1026733 

1026817 

Resize->Fullscreen dumps core 
t ext s w edit back char botch 

pressing pop-up menu button causes segmentation fault in sundiag 
diamond (Meta) key on type-4 keyboard does not work under SunView 

1026818 

1026820 

1026936 

1027435 

SunView colormap segmentation broken 
cannot place caret after last character in full panel text item 
pixwins does not alow non-power of 2 colormaps 
missing file sunwindow/cms color cube .h 

1027565 

1027642 

1027650 

1027956 

suntools.c has very poor security 

No makefile in /usr/demo/SUNVIEW/SRCS/DATA. 
first tool in SunView does not accept color 

strdup redefined in <subwindow/sun. h> producing syntax error 

1028029 

1028055 

1028073 

1028230 

Escape sequences botched by cmdtool 

typed text in colored panel text items is wrong 

libsuntool make install h misses header files 

linking dynamically with libsunwindow causes SunWrite core dump 

1028260 

1028299 

1028366 

1028588 

8 bit emulation not working in SunView 

CDROM and FACES makefiles missing dependencies 

Cursor disappears in background during fullscreen mode 
creating popup window crashes SunView tool 

1028682 

1028685 

1028688 

1028689 

double click does not work properly in editable panel text items 
caret not placed properly in editable panel text items 

The default for pending delete is TRUE in editable panel text items 

CTRL key toggle of Adjust is pending_delete fails in panel text item 

1028772 

1029033 

1029088 

1029598 

CANVAS_COLOR24 attribute generates spurious error message on CG4 

Setting WIN_SHOW to TRUE causes crash 

sundiag pop-up window does not accept any input 

swin (-g) gives win get_f ocus_event: Error 0 

1029616 

Internal API change can cause 4.x compatibility problems 


Keyword Summary of Fixed This section consists of an alphabetical list of keywords with the corresponding 
Bugs bug(s) whose fix(es) concern that keyword. 
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Table D-6 Keyword Index to Fixed Bugs 


keyword 

Relevant Bugs 

1027565 


.defaults 

1011090 

.indentpro 

1011133 

.rootmenu 

1006560 

.textswrc 

1003354,1010847 

/dev/* 

1019664 

/dev/ttyp 

1005499 

/etc/utmp 

1006591 

/usr/lib/keymaps 

1017503 

8-bit characters 

1014035 

8-bit emulation 

1028260 

8-bit fonts 

1017411 

ALERT_BUTTON_YES 

1011412 

C ANV AS_COLOR24 

1028772 

CDROM 

1028299 

CG* 

1011519,1028366,1028772, 1025804 

CTRL characters 

1003648,1010463,1013745, 1028689 

Escape sequences 

1012758,1021270,1028029 

FACES 

1028299 

FORTRAN 

1013767 

FRAMEJCON 

1016479 

Framemaker 

1018599 

GP 

1011519,1017814 

LLOC_RGNEXIT 

1009507 

LOC_WINEXIT 

1020319 

MENU_GEN_PROC 

1017887 

MENU_REPLACE_ITEM 

1015394 

Meta key 

1026817 

P ANEL_ITEM_B OXED 

1012506 

PANEL_VALUE_FONT 

1019359 

PHIGS 

1019290 

PW_DBL_EXISTS 

1011938 

SEGV 

1014179, 1026733 

SPARC 

1019891 

Sun-2 

1011973 

Sun-3 

1011973, 1017411 

Sun-386i 

1017411 

Sun-4 

1017411,1019086 

SunWrite 

1028230 

TTIN 

1003877 

WIN_FONT attribute 

1005729 

WINJSHOW 

1002759,1029033 

MENU_GEN_PROC 

1011042 

icon_load mpr 

1015181 
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Table D- 6 Keyword Index to Fixed Bugs — Continued 


keyword 

Relevant Bugs 

lockscreen 

1012023, 1025886 

pw line 

1021544 

sundiag 

1026733,1029088 

suntools 

1002411,1027565 

accelerator 

1010746 

adjust_is_pending_delete 

1028689 

alert 

1010462, 1011412,1028366 

attr.h 

1015097, 1016660 

attr_rc_units_to_pixels 

1016307 

av-lists 

1016307 

background 

1028366 

browse 

1003788 

bus error 

1006173,1008849, 1017887 

caddr_t 

1016660 

canvas 

1006173, 1009507,1012580,1017411, 1019290, 1025804, 1021544 

caret 

1009822, 1013767,1026820,1028685 

cmdtool 

1006159, 1008949,1012448, 1012695, 1013746,1020454,1021270, 
1021476, 1022841,1028029 

cms_colorcube.h 

1027435 

color 

1004586, 1012414,1012415,1018784,1027650,1028055, 1021544 

colorcube 

1026936 

colormap 

1006173, 1014075, 1014884,1026818,1026936, 1012774 

compatibility 

1029616 

confirmer 

1011412, 1028366 

console 

1002411 

core dump 

1004442, 1006652, 1007187, 1008949, 1012448,1016585, 1026613, 
1028230 


1003788 

1020719,1028588, 1029033,1025689 
1025077 

1012415, 1013767,1014075, 1017411, 1018784, 1019891,1019897, 
1019907, 1028366 _ 


defaultsedit 

1006222,1022841 

double buffer 

1007443, 1011026 

drawing 

1006341 

edit log 

1022841 

environment variables 

1004442 

events 

1020319 

fd_set 

1009284 

flags 

1002523,1012414 

fonts 

1003571, 1017411,1025689 

foreground 

1012414 

fork 

1004838, 1008199 

frame 

1002759, 1009260 
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Table D-6 Keyword Index to Fixed Bugs — Continued 


keyword 

Relevant Bugs 

frame closed 

1003581 

framebuffer 

1020319,1004221 

framebuffers 

1003850 

fullscreen 

1009357, 1026613,1028366 

gfxsw.h 

1014751 

gfxsw_select 

1014751 

hang 

1003354,1021270, 1022552 

icon 

1003571, 1009260,1021477, 1015181 

include files 

1003383, 1009284, 1027956 

infinite loops 

1005499 

install_h 

1028073 

itimer 

1003815 

keyboard 

1007620, 1026817 

keyboard focus 

1003815 

library 

1007696,1011973,1016876, 1021477, 1028073, 1028230 

lint 

1007696 

lockscreen 

1003648,1025077 

mailtool 

1009822, 1010485 

makefile 

1021476, 1028073, 1028299,1027642 

memory 

1011234 

memory leak 

1005102, 1014194, 1015394,1016479, 1020222,1023098 

menu 

1007443, 1010972, 1011412,1015167, 1026733, 1028366,1012774, 
1011042 

menu_destroy 

1015394 

menu_prompt 

1010462 

message 

1003850 

messages 

1002759,1003581, 1009354,1014935, 1019086, 1019664, 1020397, 
1029598 

mouse 

1011412, 1017411, 1028366 

nice 

1020730 

notifier 

1014194, 1029088 

notify .h 

1009284 

ntfy_ermo_abort_init 

1016820 

panel 

1003815, 1004586, 1006426, 1008457, 1017814 

panel text 

1016718, 1019359, 1026820, 1028055, 1028682, 1028685, 1028688, 
1028689 

panel.h 

1012506 

panel_destroy_item() 

1005102 

paneljtem 

1012506 

panic 

1006173, 1011853,1018785 

passwords 

1003648 

pctool 

1019086 

perform anc 

1019891 

pixfont 

1025689 
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Table D-6 Keyword Index to Fixed Bugs — Continued 


keyword 

Relevant Bugs 

pixrect 

1009260, 1019907, 1021477 

pixwin 

1006173, 1014075, 1026936 

pty 

1018963, 1020454 

pw_batch_* 

1014035 

pw_dbl_for 

1007443 

pw_dbl_write 

1007443 

pwjine 

1006341, 1018720 

pw_putcolo 

1006173 

pw_text 

1011026, 1014035 

pw_vector 

1006341 

reboot 

1011519 

rectlist.h 

1007442 

remote login 

1021270 

repaint 

1003340, 1019290 

resize 

1009357 

root menu 

1013901 

save layout 

1010557 

screenblank 

1006652, 1007620 

scroll buttons 

1012580 

scrollbar 

1008579, 1009507 

security 

1002411, 1012023, 1027565 

select system call 

1014820 

selection 

1008564, 1010485, 1010972, 1018992 

seln_create 

1019086 

set_cursor 

1019290 

shelltool 

1004442,1007187, 1009260, 1012695, 1012758, 1021476 

shift_lines 

1010522, 1010847,1011133 

signal(3) 

1012757 

split view 

1003340 

standard input 

1003877 

strdup 

1027956 

subframe 

1020719, 1023098 

subwindow 

1012757 

sun-3 

1025689 

sun-4 

1025689 

suntools 

1006173,1006217,1006560,1006591,1007696,1010557,1011234, 


1011519,1011853, 1012695, 1022552, 1004221 

sunwindowdev 

1014935 

swin 

1029598 

textedit 

1002523, 1008579, 1011384, 1013745, 1013746,1014179,1019398 

textsw 

1003354,1005729, 1008155, 1008564,1010462,1010463,1010485, 


1010847,1020222,1022841,1026708,1012020 

textsw_file_lines_visible() 

1004580 

textsw_insert 

1012577 


©sun 

XT microsystems 
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Table D-6 Keyword Index to Fixed Bugs — Continued 


keyword 

Relevant Bugs 

textsw_reset 

1020222 

toolplaces 

1010557 

tty 

1003877,1012587,1012757,1018992,1025689 

tty_argv 

1008199 

ttysw 

1004838, 1005499, 1006084, 1009260, 1013767,1026368 

values.h 

1019256 

vfork 

1004838 

win_bell.c 

1014820 

win_enumail 

1018216 

win_getnewwindow() 

1021664 

window 

1013746, 1014194, 1014935,1018216,1018785,1018992, 1019404, 
1022020, 1028588 

window display lock 

1002377 

window_create 

1006426, 1020719 

window_set 

1003581, 1014145 

windowfd 

1007696 

windows 

1009260, 1009354, 1011519, 1029088 

winio_getusercursor() 

1019897 

wraparound 

1022841 
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2 

24 bit color, see SunView 24 bit color 
24-bit color use, 31 


L 

limitations of icon_load_mpr (), 39 
limits to assigning keys, 37 


A 

additional auto_sigbits, 39 
alarms with help, 21 thru 25 
auto_sigbits, 39 

c 

color look-up table, 30 
colored panel items, 26 
colormap, 29 
CG9,29 

counting file descriptors, 38 
cursor, 34 

D 

destroying window without returning to notifier, 42 
double buffering, 30 

F 

FBIONREAD, 40 

file descriptors, counting, 38 

filename completion, 44 

FRAME_I NHERI T_COLOR behavior, 41 


G 

get_alarm, 17 

H 

help on the More Help server, 14 

I 

interposing scroll handlers, 39 

K 

keyboard support, 35 

keyword summary of fixed bugs, 48 


M 

memory leaks, 37 
memory pixrects, 32 
More Help, example, 13 
More Help, functions, 12 
multiple desktops, hardware for, 39 

N 

not all pixwin functions documented, 40 
notify_f lush__pending, 39 
null pointers, 38 

P 

panel_button_image memory, 37 
pixel colors 

translating, 31 
pixrects 

memory, 32 
plane group, 32 
pixwin and pixrect, 38 
plane group 
24-bit, 29 
8-bit, 29 
color, 29 

monochrome overlay, 29 
overlay, 30 
plane groups, 29 

pixrect-related, 32 
pointers, null, 38 
pr_putcolormap, 29 
programmable alarms, 16,16 thru 25 
programming hints, 37 thru 44 
pw_put attributes, 43 
pw_putcolormap, 29 

R 

ring_alarm, 17 
rop operations, 31 


FRAME_SHADOW and FRAME_SHOW_SHADOW incorrectly docu¬ 
mented, 40 
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Index — Continued 


s 

SCROLL_NORMALIZE attribute, 40 

secondary selections, sticky, 44 

set_alarm, 16 

sticky secondary selections, 44 

subframes, cannot iconify, 41 

summary of Sun View 1.80 bug fixes, 44 thru 53 

SunView 

8-bit color mode, 30 
SunView 1.80 update, 1 
SunView 24 bit color, 28 

. sunview and environment variable expansion, 42 
SunView CG9 command line options, 34 
SunView help mechanism, 1 thru 16 
SunView programmable alarms, see programmable alarms 

T 

TEXTSW_WRAPAROUND_SIZE attribute, 39 
. text swr c file, 35 
tools off screen, 43 
true color, 28, 29,30,31 

w 

window, destroying without returning to notifier, 42 
window_create, without error message, 42 
window_return, 38 
ws_set_favor default, 39 
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